BCI NET

home *** CD-ROM | disk | FTP | other *** search

/ BCI NET / BCI NET Dec 94.iso / archives / programming / source / jade-3.2.lha / jade-3.2 / man / jade.info-7 < prev next >

Wrap

GNU Info File | 1994-10-16 | 49.3 KB | 1,371 lines

This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. File: jade.info, Node: The Current Buffer, Prev: The Buffer List, Up: Buffers The Current Buffer ------------------ The "current buffer" is the buffer being displayed in the current window (*note Windows::.), all functions which take an optional BUFFER argument will operate on the current buffer if this argument is undefined. Similarly if a WINDOW argument to a function is left undefined the current window will be used. - Function: current-buffer &optional WINDOW Returns the buffer being displayed by the window WINDOW (or the current window). (current-buffer) => #<buffer programmer.texi> The `set-current-buffer' function sets the current buffer of a window. If, when the window is next redisplayed (i.e. after each command), the current buffer is different to what it was at the last redisplay the new buffer will be displayed in the window. - Function: set-current-buffer BUFFER &optional WINDOW Sets the buffer that the window is displaying. Usually a window's current buffer will be the buffer which is at the head of the window's `buffer-list'. The function `goto-buffer' can be used to set both of these at once. - Function: goto-buffer BUFFER Set the current buffer to BUFFER which is either a buffer or a string naming a buffer. The selected buffer is moved to the head of the window's `buffer-list'. If BUFFER is a string and no buffer exists of that name a new one is created. Often you will want to temporarily switch to a different current buffer, that is what the `with-buffer' special form is for. - Special Form: with-buffer BUFFER FORMS... Temporarily sets the current buffer to the value of evaluating BUFFER, then evaluates the FORMS in sequence. The old value of the current buffer is reinstated and the structure returns the value of the last of the FORMS to be evaluated. If the implicit progn evaluating FORMS is exited abnormally the old value of the current buffer will still be reinstated. If the window is redisplayed while the FORMS are being evaluated (i.e. in a recursive edit) the new buffer will be drawn into the window. (with-buffer new-buffer ;Enter a recursive edit in (recursive-edit)) ; the buffer `new-buffer'. File: jade.info, Node: Windows, Next: Positions, Prev: Buffers, Up: Programming Jade Windows ======= A "window" is a Lisp object representing a window (a rectangular section of the display) open in the windowing-system you are running Jade in. Windows have two main functions, firstly to provide a means of seeing the contents of a buffer and secondly to receive input events. For more details about event handling see *Note Event Loop::. A window *always* displays a buffer and there is *always* at least one window open. The editor remembers which of the open windows is the "current window", this is normally the window it last received an input event from, though it can be set by programs. For some basic details about using windows see *Note Using Windows::. - Function: windowp OBJECT This function returns `t' if its argument is a window. - Variable: window-list This variable's value is a list of all the currently open windows. The order of the elements in the list is insignificant. window-list => (#<window 20971528 *Info*> #<window 20971524 *jade*>) * Menu: * Opening Windows:: Creating new windows * Closing Windows:: Deleting windows * Iconifying Windows:: Temporarily removing windows * Displaying Messages:: Messages to the user * The Current Window:: The activated window, used by default * Window Font:: Each window may use a different font * Window Information:: Details of a window's current state * Rendering:: How buffers are drawn in windows * Block Marking:: Highlighting a region of a window File: jade.info, Node: Opening Windows, Next: Closing Windows, Up: Windows Opening Windows --------------- - Function: open-window &optional BUFFER X Y WIDTH HEIGHT Opens a new window and returns it. If BUFFER is defined it is the buffer to display in the new window, otherwise the current buffer is displayed. The X and Y arguments are the pixel coordinates of the new window's top left corner in the display. The WIDTH and HEIGHT arguments are the size of the window in columns and rows of characters respectively. What happens when the position and size of the window is undefined will depend on the underlying window system, on the Amiga the window will probably be the same as the current window, in X11 the window manager will probably let the user size it interactively. The new window will have its `buffer-list' variable initialised suitably and it will be added to the head of the `window-list' variable. The `make-window' function is the lowest level of creating a new window, `open-window' uses it to open the window. - Function: make-window &optional X Y WIDTH HEIGHT Creates a new window and returns it, the arguments are similar to those of the same name in the `open-window' function. The window will display the current buffer. After the window is created the `make-window-hook' will be called with the window as its argument. - Hook: make-window-hook Hook called each time a new window is created. It has one argument, the new window. - Variable: pub-screen This window-local variable is only used on the Amiga version of Jade; it holds the name of the public screen which windows are opened on. By default this is the Workbench screen. When a window is opened it inherits this value from the current window at the time. File: jade.info, Node: Closing Windows, Next: Iconifying Windows, Prev: Opening Windows, Up: Windows Closing Windows --------------- Unlike buffers, window objects don't have indefinite extent, even when a window is incapable of being referenced the object will not be destroyed by the garbage collector; count the user looking at the window as a reference! When the window is closed (by the `destroy-window' function) the object loses its `window-ness' and the garbage collector is free to reclaim its memory. - Function: close-window &optional WINDOW This function closes the window WINDOW (or the current window) and deletes its entry from the `window-list' variable. If this window is the only one the editor has open the user is asked if it's okay to lose any modified buffers before the window is closed. - Function: close-other-windows &optional WINDOW Uses `close-window' to close all windows except WINDOW (or the current window). - Function: destroy-window WINDOW Closes the window WINDOW. After a window object has been closed it is no longer a member of the type `window'. Before closing the window the `destroy-window-hook' is evaluated with the window being destroyed as an argument. When the last window is closed the editor will exit automatically. Like the `destroy-buffer' function, this function is dangerous if used carelessly. Both `close-window' and `close-other-windows' eventually call this function. - Hook: destroy-window-hook Hook called by `destroy-window' before it does anything. It has one argument -- the window to be destroyed. File: jade.info, Node: Iconifying Windows, Next: Displaying Messages, Prev: Closing Windows, Up: Windows Iconifying Windows ------------------ When you don't want a window cluttering the display, but don't want to kill it totally it can be iconified; the window will be displayed as a small icon which can be reactivated when the window is wanted again. - Function: sleep-window &optional WINDOW Iconifies the specified window. - Function: unsleep-window &optional WINDOW Uniconifies the specified window. This may be done automatically if the user needs to be prompted. - Function: toggle-iconic Toggles the current window between the iconified and normal states. This command is bound to the key sequence `Ctrl-z'. - Function: window-asleep-p Returns `t' when the current window is iconified. File: jade.info, Node: Displaying Messages, Next: The Current Window, Prev: Iconifying Windows, Up: Windows Displaying Messages ------------------- Often it is useful to be able to show the user a short one-line message, this is what the `message' function does. - Function: message MESSAGE &optional DISPLAY-NOW This function displays the string MESSAGE in the status line of the current window, then returns MESSAGE. If DISPLAY-NOW is non-`nil' the message is rendered into the window immediately, otherwise it will not be visible until the next general redisplay (usually after each command exits). Note that an alternate way of writing in the status line is to use the output stream `t'. *Note Output Streams::. When writing interactive programs it is sometimes useful to be able to render the cursor in the status line. This shows that the next key press will not be subject to normal editing key bindings but to the special user interface (usually explained by a message in the status line). For example the `y-or-n-p' function uses this technique to show that it needs an answer. - Variable: status-line-cursor When this window-local variable is non-`nil' the window's cursor is rendered at the end of the message in the status line, not at the cursor's position in the main display. Another way of alerting the user is to use the `beep' function, - Function: beep This function rings a bell or flashes the current window or screen depending on your system. File: jade.info, Node: The Current Window, Next: Window Font, Prev: Displaying Messages, Up: Windows The Current Window ------------------ The current window is the window that functions operate on by default; every time the event loop receives some input from the user the window which the input event originated in becomes the current window. It is also possible for Lisp programs to set the current window, either permanently or temporarily. The "active window" is the window which the windowing system will send any keyboard input to. Since Jade sets the current window to where it receives input from, it is often the case that the current window is the same as the active window. Jade also provides the means to set the active window; in some cases this may be best left to the user though. - Function: current-window This function returns the current window. (current-window) => #<window 20971524 programmer.texi> - Function: set-current-window WINDOW &optional ACTIVATE This function sets the current window to be the window WINDOW. If the optional argument ACTIVATE is non-`nil' this window will also become the active window. When using the ACTIVATE argument bear in mind that it may be confusing for the user if the active window is suddenly changed; only change the active window synchronously with some input from the user. - Special Form: with-window WINDOW FORMS... Temporarily sets the current window to the value of evaluating the form WINDOW, then uses an implicit progn to evaluate the FORMS. The old current window is then reinstated before returning the value of the implicit progn. File: jade.info, Node: Window Font, Next: Window Information, Prev: The Current Window, Up: Windows Window Font ----------- Each window may use a different font; this font will be used for rendering all text in the window. When windows are created they inherit their font from the current window at the time. Currently Jade only allows the use of fixed-width fonts; proportional fonts won't work properly. - Command: set-font FONT-NAME &optional WINDOW This function sets the font used in the window WINDOW (or the current window) to the font named by the string FONT-NAME. The format of the string FONT-NAME depends on the underlying windowing system: X11 Simply use the standard name of the font, asterisk characters work like usual (i.e. match zero or more characters). Amiga This is different to the normal Amiga conventions, use the name of the font followed by a dash and then the size of the font. For example to get an 8-point topaz font, use `topaz.font-8'. When this function is called interactively it will prompt for FONT-NAME. - Function: font-name &optional WINDOW Returns the name of the font being used in the specified window. Note that on an Amiga this will only return the name, and not the size of the font. For example, if `set-font' has been used with an argument of `"topaz.font-8"', a call to `font-name' would produce `"topaz.font"'. - Function: font-x-size &optional WINDOW Returns the width (in pixels) of a character in the specified window's font. (font-x-size) => 7 - Function: font-y-size &optional WINDOW Returns the height in pixels of each character in the window's font. (font-y-size) => 13 File: jade.info, Node: Window Information, Next: Rendering, Prev: Window Font, Up: Windows Window Information ------------------ There are a number of functions which provide information about the current state of a window. - Function: window-id &optional WINDOW Returns an integer which is the window system's `handle' on the window WINDOW (or the current window). Under X11 this is the Window identifier, on an Amiga it's a pointer to the window's `struct Window'. (window-id) => 20971524 - Function: window-count Returns the number of currently-opened windows. - Function: screen-width Returns the width of the root window or screen in pixels. - Function: screen-height Returns the height in pixels of the root window. - Function: window-left-edge Returns the x coordinate of the current window relative to the root window's top-left corner. - Function: window-top-edge The y coordinate of the current window relative to the root window's top-left corner. - Function: window-width Returns the width, in pixels, of the current window. - Function: window-height Returns the height in pixels of the current window. - Function: window-bar-height Only used by Amigas, this returns the height of the current window's title bar. This will always be zero in X. - Function: screen-top-line Returns the line number of the first line being shown in the current window. - Function: screen-bottom-line Returns the line number of the last line being shown in the current window. - Function: screen-first-column Returns the column number of the first column being shown in the current window. - Function: screen-last-column Returns the column number of the last column being shown in the current window. File: jade.info, Node: Rendering, Next: Block Marking, Prev: Window Information, Up: Windows Rendering --------- After each command is executed a full redisplay is done; the display of each window is made to be consistent with the contents of the buffer it is showing. - Function: refresh-all This function calls the redisplay code, any windows, whose display is inconsistent with what it should be displaying, are updated. - Function: cursor ON Turns the cursor in the current window on or off (depending on whether ON is non-`nil' or not). Normally the cursor is erased while Lisp programs are executing. If you use this function be sure to leave the cursor undrawn when you've finished. - Function: centre-display &optional WINDOW If possible, this function will arrange it so that the line which the cursor is on (*note The Cursor Position::.) will be in the centre of the display. - Function: next-screen &optional COUNT Move COUNT (or 1 by default) screens forwards in the display, Lisp programs shouldn't need to call this. - Function: prev-screen &optional COUNT Move COUNT screens backwards in the display. Don't call this from Lisp programs. - Function: flush-output This function forces any locally-cached rendering operations to be drawn into the actual window. This should be called after any use of the `refresh-all' or `cursor' functions. Currently this function only actually does anything in the X11 version of Jade (it calls XFlush()), but to ensure the portability of Lisp programs it should be used anyway. - Variable: max-scroll This window-local variable defines the maximum number of lines which may be scrolled in one go; if more than this number of lines have to be moved when a redisplay happens the whole window will be redrawn. - Variable: y-scroll-step-ratio This window-local variable controls the actual number of lines scrolled when the cursor moves out of the visible part of the window. The number of lines to move the display origin is calculated with the formula: (/ TOTAL-LINES-IN-WINDOW y-scroll-step-ratio) If the variable's value is zero then the window will be scrolled by the least number of lines necessary to get the cursor back into the visible part. - Variable: x-scroll-step-ratio Similar to `y-scroll-step-ratio', except that it's used when the cursor disappears to the left or the right of the display. File: jade.info, Node: Block Marking, Prev: Rendering, Up: Windows Block Marking ------------- Each window may define one "block", this is a region of the buffer displayed in the window which is rendered in the opposite colours to normal (i.e. the same as the normal cursor, when the cursor is in a block it's drawn in the inverse of the block). Blocks are primarily used for marking areas of a buffer which will subsequently be manipulated. Normally the area of the buffer contained by a block is delimited by two positions; the start and end of the block (these will track changes made to the buffer and adjust themselves, like marks do). It is also possible to mark rectangular blocks; these are also delimited by two positions, but they define the two opposite corners of the rectangular block. - Function: blockp Returns `t' if a block is marked in the current window. - Function: mark-block START-POS END-POS Define the beginning and end markers of the block to display in the current window. - Command: block-kill Unmark the block displayed in the current window. - Command: mark-word COUNT &optional POS Mark COUNT words from POS (or the cursor pos) in the current window. - Command: mark-whole-buffer Mark the whole of the current buffer. - Function: block-start Returns the position of the beginning of the block marked in the current window. If no block is defined returns `nil'. - Function: block-end Returns the position of the end of the block, or `nil' if no block is defined in the current window. - Command: block-toggle Toggles between marking the beginning, marking the end and totally unmarking the block in the current window. - Function: rect-blocks-p &optional WINDOW Returns `t' if the block marked in the window is drawn as a rectangle. - Function: set-rect-blocks WINDOW STATUS Defines whether or not the block drawn in WINDOW is drawn as a rectangle or not. If STATUS is `nil' it isn't. - Command: toggle-rect-blocks Toggles between marking normal and rectangular blocks in the current window. File: jade.info, Node: Positions, Next: Marks, Prev: Windows, Up: Programming Jade Positions ========= A "position" is a Lisp object representing the location of one of the characters in the contents of a buffer (*note Buffers::.). Since Jade stores buffer contents as an array of lines, two index values are needed to reference a single character. A position object contains two integers; the column and line numbers of the character, both these values count upwards from zero (i.e. the first character in a buffer has line and column numbers of zero). Position objects have no read syntax; they print as, #<pos COLUMN LINE> - Function: posp OBJECT This function returns `t' when its argument is a position object. - Function: pos COLUMN LINE Creates and returns a new position object, it points to column number COLUMN and line number LINE (both integers). - Function: copy-pos POS Creates a new copy of the position object POS. * Menu: * Position Components:: Accessing the members of a position * The Cursor Position:: Where the cursor is drawn in the display * Movement Functions:: Position-motion functions * Positions and Offsets:: Converting between positions and buffer offsets File: jade.info, Node: Position Components, Next: The Cursor Position, Up: Positions Position Components ------------------- As previously noted, each position object has two components; one number defining the column, the other defining the line that the position represents. These components can be accessed individually. - Function: pos-col POS Returns the column which the position object POS points to. (pos-col (pos 1 2)) => 1 - Function: pos-line POS This function returns the line number which POS points to. - Function: set-pos-col POS NEW-COL Sets the number of the column which the position object POS points to, to NEW-COL (an integer), then returns col. (setq x (pos 1 2)) => #<pos 1 2> (set-pos-col x 3) => 3 x => #<pos 3 2> - Function: set-pos-line POS NEW-LINE Similar to `set-pos-col' except the line number is modified. File: jade.info, Node: The Cursor Position, Next: Movement Functions, Prev: Position Components, Up: Positions The Cursor Position ------------------- Each window displays a "cursor", this is rendered as a character in the opposite colour to what it would usually be (i.e. normally a dark rectangle). The cursor is used to show the user where any characters they type will be inserted, each window has a separate cursor position and buffers which are not being displayed `remember' the last position of their cursor. - Function: cursor-pos This function returns a copy of the cursor position in the current window. (cursor-pos) => #<pos 14 5638> - Function: goto-char POS Sets the position of the current window's cursor to the position object POS, then returns POS. Note that the components of POS are *copied*, any subsequent modification of POS will not affect the cursor. If the line number of POS points to a non-existent line the cursor won't be moved and `nil' will be returned. File: jade.info, Node: Movement Functions, Next: Positions and Offsets, Prev: The Cursor Position, Up: Positions Movement Functions ------------------ This section documents the functions which are used to create and modify position objects so that they point to a different position which is related to the original position in some way. The functions which begin `goto-' set the cursor position of the current window to the new position; the others do *not* move the cursor, they simply calculate the new position and return it. In some cases the position argument itself will be modified and returned, this may cause confusion; if there are existing references to the object they subtle bugs may result. Consider the following, (setq x (cursor-pos) y (next-char 1 x)) At first glance this looks as though the variable `y' will point to one character after the variable `x' does. Since the `next-char' function *modifies* its argument position *both* variables will contain the same object, and therefore, point to the same position. A solution is, (setq x (cursor-pos) y (next-char 1 (copy-pos x))) Read each function's description carefully to see if it alters its arguments! * Menu: * Buffer Extremes:: The edges of a buffer * Character Movement:: Moving in terms of characters, * Word Movement:: or maybe words, * Tab Movement:: tabs, * Line Movement:: lines, * Expression Movement:: or even expressions. File: jade.info, Node: Buffer Extremes, Next: Character Movement, Up: Movement Functions Buffer Extremes ............... - Function: buffer-end &optional BUFFER Create and return a new position object pointing to the character after the last character in the buffer. - Function: goto-buffer-end Set the cursor to the character after the last character in the current buffer. - Function: buffer-start &optional BUFFER Create a new position pointing to the first character in the buffer. Currently this is always the position `#<pos 0 0>' and the BUFFER argument is ignored. - Function: goto-buffer-start Set the cursor position to the first character in the buffer. File: jade.info, Node: Character Movement, Next: Word Movement, Prev: Buffer Extremes, Up: Movement Functions Character Movement .................. - Function: left-char &optional COUNT POS Alter and return POS (or a copy of the cursor pos) so that it points COUNT characters (default is one) to the left of its current position. If the resulting column number is less than zero `nil' is returned, else the position. (goto-char (pos 20 0)) => #<pos 20 0> (left-char) => #<pos 19 0> (setq x (pos 4 1)) => #<pos 4 1> (left-char 3 x) => #<pos 1 1> x => #<pos 1 1> - Function: goto-left-char &optional COUNT Move COUNT (or one) characters to the left. - Function: right-char &optional COUNT POS Alter and return POS (or a copy of the cursor pos) so that it points COUNT (or one) characters to the right of its current position. May return a position which points to a character past the end of the line. - Function: goto-right-char &optional COUNT Move COUNT (or one) characters to the right. The following functions results depends on the contents of the buffer they are operating on; they move a certain number of *characters*, and hence will cross line boundaries. - Function: next-char &optional COUNT POS BUFFER Alter and return POS (or a copy of the cursor pos) to point to the character COUNT characters in front of its current position. If COUNT is negative this function will work backwards through the buffer. - Function: goto-next-char &optional COUNT Move COUNT characters forwards. - Function: prev-char &optional COUNT POS BUFFER Similar to the `next-char' function but will work backwards when COUNT is positive and forwards when it is negative. - Function: goto-prev-char COUNT Move COUNT characters backwards. File: jade.info, Node: Word Movement, Next: Tab Movement, Prev: Character Movement, Up: Movement Functions Word Movement ............. There are two buffer-local variables which control the syntax of words in each buffer. - Variable: word-regexp This buffer-local variable contains a regular expression which will match each character allowed to be in a word. The standard value is `[a-zA-Z0-9]', i.e. all alphanumeric characters. - Variable: word-not-regexp A buffer-local variable. Holds a regular expression which will match anything not in a word. The normal value is `[^a-zA-Z0-9]|$', i.e. anything which is not alphanumeric or the end of a line. The following functions use these variables when deciding what is and what isn't a word. - Function: forward-word &optional COUNT POS MOVE Return the position of the first character after the end of the word at position POS (or the cursor). COUNT is the number of words to move, negative values mean go backwards. If MOVE is non-`nil' then the cursor is moved to the result. Note that POS is not altered. - Function: backward-word &optional COUNT POS MOVE Similar to `forward-word' except that it works backwards. In fact, all this function does is call `forward-word' with COUNT negated. - Function: word-start &optional POS Returns the position of the first character of the word at POS (or the cursor position). - Function: in-word-p &optional POS This function returns `t' if POS (or the cursor) is in a word. File: jade.info, Node: Tab Movement, Next: Line Movement, Prev: Word Movement, Up: Movement Functions Tab Movement ............ - Function: prev-tab &optional COUNT POS SIZE Alter and return POS (or a copy of the cursor position) so that it points COUNT (default is one) tab stops to the left of its current position. Returns `nil' if that position is before the start of the line. SIZE is optionally the number of glyphs in each tab, or the value of the `tab-size' variable. Note that the position returned is not the position of a character but of a glyph (*note Glyph Positions::.). (prev-tab 1 (pos 20 0)) => #<pos 16 0> - Function: goto-prev-tab &optional COUNT SIZE Move COUNT tab stops to the left. - Function: next-tab &optional COUNT POS SIZE Alter and return POS (or a copy of the cursor position) so that it points COUNT tab stops to the right of its current position. SIZE is optionally the number of glyphs in each tab, or the value of the `tab-size' variable. Note that the position returned is not the position of a character but of a glyph (*note Glyph Positions::.). - Function: goto-next-tab &optional COUNT SIZE Move COUNT tab stops to the right. File: jade.info, Node: Line Movement, Next: Expression Movement, Prev: Tab Movement, Up: Movement Functions Line Movement ............. - Function: next-line &optional COUNT POS Alter and return POS (or a copy of the cursor position) so that it points COUNT (or one) lines forwards, the column component is not changed. If COUNT is negative (i.e. go backwards) and the resulting line number is less than zero `nil' is returned. (next-line 2 (pos 1 1)) => #<pos 1 3> (next-line -1 (pos 1 1)) => #<pos 1 0> - Function: goto-next-line &optional COUNT Move COUNT lines downwards, the column number of the cursor is adjusted so that its glyph position is as close to its previous glyph position as possible. - Function: prev-line &optional COUNT POS Similar to NEXT-LINE but goes backwards (or forwards with a negative COUNT). - Function: goto-prev-line &optional COUNT Move COUNT lines backwards, adjusting the column number of the cursor as necessary. File: jade.info, Node: Expression Movement, Prev: Line Movement, Up: Movement Functions Expression Movement ................... Some major modes provide functions to move backwards and forwards over expressions written in a buffer in the programming language that the mode supports (*note Mode-Specific Expressions::.), for example the Lisp mode defines the syntax of Lisp forms written in a buffer. - Function: forward-exp &optional COUNT This function moves the cursor over COUNT expressions, as defined in the current buffer. If the buffer has no expression definitions an error is signalled. - Function: backward-exp &optional COUNT Moves backwards over COUNT (or one) expressions, leaving the cursor at the beginning of the expression. If the buffer has no expression definition functions an error is signalled. File: jade.info, Node: Positions and Offsets, Prev: Movement Functions, Up: Positions Positions and Offsets --------------------- Although Jade stores the position of a character as a pair of two numbers many other programs define the position of a character as its offset from the beginning of the buffer or file it is in. The following functions may be used to convert between these two types of positions in a specified buffer. - Function: pos-to-offset &optional POS BUFFER This function returns the offset of the character at the position POS (or the cursor position by default) in the specified buffer. This will be an integer, the first character in a buffer is represented by an offset of zero. (pos-to-offset (pos 0 0)) => 0 (pos-to-offset) => 195654 - Function: offset-to-pos OFFSET &optional BUFFER Creates a new position object which contains the position of the character OFFSET characters from the start of the specified buffer. (offset-to-pos 0) => #<pos 0 0> (offset-to-pos 195654) => #<pos 14 5974> File: jade.info, Node: Marks, Next: Glyph Tables, Prev: Positions, Up: Programming Jade Marks ===== A "mark" is a Lisp object which points to a character in a file (or buffer), as the buffer the file is stored in is modified the position the mark points to is also modified so that the mark will *always* point to the same character. The character that a mark points to does not have to be loaded into the editor all the time either; if the file the character is in is not resident in a buffer the mark will simply contain the character's position and the file's name. When a file is loaded any marks pointing to the file are altered so that they point straight to the buffer containing the file. - Function: markp OBJECT This function returns `t' if its argument is a mark. * Menu: * Mark Components:: Marks contain two values; position and file * Mark Relocation:: How the position of a mark is updated as its buffer is modified * Mark Residency:: Marks may point to files which have not been loaded * Creating Marks:: Functions to allocate new mark objects * Altering Marks:: Setting the components of a mark * Moving to Marks:: Moving the cursor to the character a mark points to File: jade.info, Node: Mark Components, Next: Mark Relocation, Up: Marks Mark Components --------------- Each mark object has two main components; the position of the character pointed to by the mark (a position object) and the file which the character is contained by. The file is the most complex component, it can be either a string naming the file or a buffer. When the file component is a string the mark is said to be "non-resident" since none of the editor buffers contain the character which the mark points to. - Function: mark-pos MARK Returns the position object contained in the marker MARK, no copy is made: if you modify the position returned it will be reflected in the position of the mark. Note that if you later modify the buffer the mark is resident in the position previously returned by `mark-pos' may be altered by the mark relocation process. *Note Mark Relocation::. - Function: mark-file MARK Returns the file component of MARK. This will be either the name of the file or the buffer itself depending on whether the mark is resident or not. *Note Mark Residency::. File: jade.info, Node: Mark Relocation, Next: Mark Residency, Prev: Mark Components, Up: Marks Mark Relocation --------------- An important feature of marks is that they always point to the same character, even when the buffer has been modified, changing the position of the character (i.e. if some text is deleted from somewhere before the character its position will probably change). Every time a buffer is modified each mark which points to a character in that buffer is examined and then, if necessary, the position it points to is changed to take account of the buffer's new state. Basically, what happens is that each mark will try to point at the same character all the time. If some text is inserted at the position of the mark the mark's position will be advanced to the end of the insertion and hence the original character. The only time the mark will not point at the same character is when the character is deleted from the buffer. In this case the mark will point to the start of the deletion. File: jade.info, Node: Mark Residency, Next: Creating Marks, Prev: Mark Relocation, Up: Marks Mark Residency -------------- As I have already explained, a mark does not necessarily have to point at a character loaded into a buffer; it can also point at a character in a file on disk somewhere. When this happens the mark is said to be non-resident. - Function: mark-resident-p MARK This function returns `t' when the character pointed to by the marker MARK is resident in one of the editor's buffers. When the function `mark-file' (*note Mark Components::.) is applied to a non-resident mark it returns the full name of the file, for example, (setq x (make-mark (pos 0 20) "/tmp/foo.c")) => #> (mark-resident-p x) => nil (mark-file x) => "/tmp/foo.c" When a file is loaded into a buffer all existing non-resident marks are examined to see if they point to that file. If so that mark has its file component set to the buffer that the file was loaded into. Similarly, when a buffer is deleted any marks pointing to characters in that buffer are made non-resident: their file component is set to the name of the file. When the function which moves the cursor to the position of a specific mark (`goto-mark', *note Moving to Marks::.) is called with a non-resident mark it will try to load the file into a buffer. The following code fragment can be used to ensure that a mark MARK is resident, (or (mark-resident-p MARK) (open-file (mark-file MARK)) (error "Can't make mark resident, %S" MARK)) File: jade.info, Node: Creating Marks, Next: Altering Marks, Prev: Mark Residency, Up: Marks Creating Marks -------------- - Function: make-mark &optional POS BUFFER-OR-FILENAME This function allocates a new mark object and fills it in according to the supplied arguments. It will point at a character at position POS, or the position of the cursor in the current window. Note that a copy of POS is made. The BUFFER-OR-FILENAME argument specifies the file component of the mark. If BUFFER-OR-FILENAME is a buffer (`nil' or undefined means the current buffer) the mark will use it and therefore will be resident (*note Mark Residency::.). Alternatively, BUFFER-OR-FILENAME can be a string naming the file explicitly. If the file is already loaded into a buffer that buffer will be used and the mark will be resident. Otherwise the mark will be non-resident and the string will be used as the file component. With no arguments this function will produce a resident mark pointing at the cursor in the current buffer. (make-mark) => # #<pos 46 6152>> (make-mark (buffer-start) "/tmp/foo") => #> (make-mark (pos 0 3)) => # #<pos 0 3>> File: jade.info, Node: Altering Marks, Next: Moving to Marks, Prev: Creating Marks, Up: Marks Altering Marks -------------- If you just want to set the position of a mark you can modify its position component (*note Mark Components::.). Alternately the following function may be used. When you need to set the file a mark points to the only method is to use this function. - Function: set-mark MARK &optional POS BUFFER-OR-FILENAME This function sets either or both of the position and file components of the mark object MARK, then returns MARK. If POS is a position object the position component of MARK will be set to it (a copy of it actually). If the BUFFER-OR-FILENAME argument is non-`nil' the file component of MARK will be set. This argument can be a buffer object or a string naming a file. If a named file is already in a buffer that buffer will be used instead. (setq x (make-mark)) => # #<pos 46 6186>> (set-mark x (buffer-start)) => # #<pos 0 0>> (set-mark x nil "/tmp/foo") => #> File: jade.info, Node: Moving to Marks, Prev: Altering Marks, Up: Marks Moving to Marks --------------- - Function: goto-mark MARK This function switches to the buffer containing MARK (if necessary) and then moves the cursor to the character that the mark points to. If the mark is not currently resident an attempt will be made to load the mark's file into a new buffer and use that. File: jade.info, Node: Glyph Tables, Next: Input Events, Prev: Marks, Up: Programming Jade Glyph Tables ============ A "glyph table" is a Lisp object used to define a mapping between the characters which may occur in a buffer (anything with a numeric value between 0 and 255 inclusive) and the sequences of glyphs which are drawn into a window to represent these characters. A "glyph" is a image which, when rendered into the display, takes up one character position. Each character in a buffer is rendered as a sequence of 1 or more glyphs. - Function: glyph-table-p OBJECT This function returns `t' when its argument is a glyph table. * Menu: * Glyph Table Basics:: How a glyph table defines mappings * Glyph Positions:: The position of a character and its glyph sequence may be different * Creating Glyph Tables:: Making new glyph tables * Buffer Glyph Tables:: Each buffer may use a separate glyph table for its display File: jade.info, Node: Glyph Table Basics, Next: Glyph Positions, Up: Glyph Tables Glyph Table Basics ------------------ A glyph table is basically an array that has 256 elements; each element represents one character and contains between zero and four glyphs -- the glyphs which will be printed for the character. A special case exists for the tab character; when an element in the table contains zero glyphs, enough spaces will be printed to fill in to the next tab stop. - Function: get-glyph GLYPH-TABLE CHARACTER This function returns a string containing the glyphs in the element of the glyph table GLYPH-TABLE for the character CHARACTER. (get-glyph (default-glyph-table) ?a) => "a" (get-glyph (default-glyph-table) ?\t) => "" ;TAB is special (get-glyph (default-glyph-table) ?\000) => "^@" ;the NUL character - Function: set-glyph GLYPH-TABLE CHARACTER GLYPH-STRING This function sets the sequence of glyphs used to render the character CHARACTER in the glyph table GLYPH-TABLE to the characters in the string GLYPH-STRING. An error is signalled if there are more than four characters in GLYPH-STRING. All buffers which use GLYPH-TABLE for their rendering will be totally redrawn at the next redisplay. File: jade.info, Node: Glyph Positions, Next: Creating Glyph Tables, Prev: Glyph Table Basics, Up: Glyph Tables Glyph Positions --------------- Position objects are usually used to refer to the position of a character in a buffer, this position (sometimes called the "character position" may not be the same as the position of the sequence of glyphs printed to represent the character. When a position object is used to refer to the position of a glyph it is called a "glyph position". For example, consider a line in a buffer containing the string `a\tb' (where `\t' represents a tab character). When this is rendered in a buffer the glyphs which will actually be drawn are, a b That is, an `a' glyph, followed by seven (assuming `tab-size' is set to 8) ` ' glyphs, and lastly a `b' glyph. The character position of the `b' character in the buffer is `#<pos 2 LINE>', where LINE is the line's number. Now the confusing bit: the *glyph* position of the `b' *glyph* is `#<pos 8 LINE>' since it is actually the ninth glyph to be drawn. The good news is that most of the time you can forget about glyph positions, they only need to be considered when you're thinking about how the buffer will look when rendered in the window. For example, Lisp programs which indent source code will definitely need to use glyph positions. Two functions are provided for converting between character and glyph positions and vice versa. - Function: char-to-glyph-pos &optional POS BUFFER Return a new position object containing the glyph position of the character at character position POS (or the cursor position) in the specified buffer. - Function: glyph-to-char-pos POS &optional BUFFER This function returns a new position object containing the character position of the glyph printed at glyph position POS in the specified buffer. If the glyph position POS is not the position of the first in a sequence of glyphs representing a single character the position of the next character will be returned. File: jade.info, Node: Creating Glyph Tables, Next: Buffer Glyph Tables, Prev: Glyph Positions, Up: Glyph Tables Creating Glyph Tables --------------------- - Function: make-glyph-table SOURCE This function creates a new glyph table, containing glyph sequences defined by the SOURCE argument. If SOURCE is a glyph table it will be copied, if it's a buffer that buffer's glyph table will be copied or if SOURCE is `nil' a copy of the default glyph table will be made. File: jade.info, Node: Buffer Glyph Tables, Prev: Creating Glyph Tables, Up: Glyph Tables Buffer Glyph Tables ------------------- Each buffer may define its own glyph table that will be used to provide the character-to-glyph mappings for that buffer. - Function: buffer-glyph-table &optional BUFFER Returns the glyph table installed in the buffer. - Function: set-buffer-glyph-table GLYPH-TABLE &optional BUFFER Sets the glyph table being used in the buffer to GLYPH-TABLE. By default, each buffer uses the "default glyph table". This is a glyph table set up when the editor initialise itself. The mappings it provides are very generic, for more details see *Note Character Images::. - Function: default-glyph-table This function returns the default glyph table. Redefining some of the mappings in the default glyph table is an easy way to affect rendering operations, for example if I want the UK pound sign character (ASCII value is octal 243) to be printed as itself and not the usual escape sequence I can do the following, (set-glyph (default-glyph-table) ?243 "\243") File: jade.info, Node: Input Events, Next: Keymaps, Prev: Glyph Tables, Up: Programming Jade Input Events ============ An "input event" is a Lisp object representing an action initiated by the user, i.e. a key press, pressing a mouse button and similar things. Note that input events are often referred to as key presses, this isn't really accurate but since most input events are key presses the term sort of stuck. Anyway, wherever the phrase `key press' occurs in this manual it could be replaced by `input event'. Each input event is represented by a cons cell (*note Cons Cells::.) containing two integers, these integers encode the actual input event. The encoding is opaque; the only way to access an event meaningfully is via the functions provided. - Function: eventp OBJECT This function returns `t' if its argument is an input event. Each event has a textual name, for the actual format of these names see *Note Key Names::. Functions are available to convert between the name of an event and the actual event itself, and vice versa. - Function: lookup-event EVENT-NAME Create and return a new input event whose name is EVENT-NAME. (lookup-event "Ctrl-x") => (120 . 9) (lookup-event "Ctrl-Meta-LMB-Click1") => (1 . 58) - Function: event-name EVENT This function returns a string naming the input event EVENT. (event-name (lookup-event "Ctrl-x")) => "Ctrl-x"